Configuration File

ApertureDB reads server settings from a JSON configuration file. The -cfg flag specifies its path:

./aperturedb -cfg config.json

Without -cfg, ApertureDB reads config.json from the working directory. The server does not start if the file is missing.

Parameters

All configuration keys are optional. Omitted settings use environment variables or built-in defaults according to the precedence below.

For settings read by the server, the first available value is used:

A nonempty environment variable with prefix ADB_ and the key in upper case, such as ADB_PORT or ADB_SESSION_TOKEN_MAX_AGE_SEC.
The value in the JSON configuration file.
The server’s built-in default.

An empty environment variable falls through to JSON or the default. Use true/false for boolean environment values, decimal numbers for numeric values, and raw text for strings. Do not add JSON quotes around string values in the environment. Shell or deployment-file quoting is separate.

The JSON file is parsed and validated before environment overrides are read. Unknown keys, wrong JSON types, and out-of-range JSON values prevent startup even when an environment variable would override them. Environment values are parsed when the consuming setting is read; the JSON validator does not validate the final merged configuration. Follow the documented ranges for both sources. Restart the consuming process after configuration changes.

These defaults describe the database binary. Deployment packages supply additional values and configure separate processes; see Deployment settings and process boundaries.

The following table describes commonly used parameters:

Parameter	Explanation	Default
master_key	The master key that initializes admin password on the first run.	`""` (Range: any string)
port	TCP port for incoming connections	55555 (Range: 1-65535)
enable_health_port	Enable/disable the health check port	false (Range: true/false)
health_port	TCP port for health checks	55563 (Range: 1-65535)
timeout_receive	Enable/disable connection receive timeouts	true (Range: true/false)
max_simultaneous_clients	Number of max simultaneous connections open	500 (Range: >= 1)
max_connection_message_size_mb	Maximum native query/response message size in MiB (1,048,576 bytes). A value of 0 uses the libcomm default. This does not set HTTP proxy limits.	0 (Range: >= 0)
force_ssl	Flag that indicates whether or not SSL-based communication will be enforced by the server	true (Range: true/false)
db_root_path	Path to the root folder where all files/objects will be stored	db (Range: any valid path)
storage_type	Storage backend: `ext4` for local files, `s3` for S3, or `gs` for Google Cloud Storage.	`"ext4"`
storage_bucket_name	Bucket name for S3 or Google Cloud Storage.	`""`
storage_credentials	Storage credential JSON encoded as a string. See Deploying ApertureDB for credential examples.	`"{}"`
log_path	Directory where logs will be placed.	`"/tmp"` (Range: any valid path)
log_level	Levels INFO, WARNING, ERROR, and FATAL are 0, 1, 2, and 3, respectively	1 (WARNING) (Range: 0-3)
verbose_log_level	Verbosity level beyond INFO, for debugging. Will set log_level = 0. Check Google glog documentation for details	-1 (no verbosity beyond INFO) (Range: >= -1)
log_cerr_threshold	Specify level of logging which will also be sent to stderr	3 (FATAL) (Range: 0-3)
enable_audit_logs	Enable/disable audit logs	false (Range: true/false)
include_audit_logs	When true, audit logs will be included in ApertureDB logs	false (Range: true/false)
kvgd_db_size	Maximum size of the graph database in MB	10 (Range: > 0)
kvgd_db_sync	Enable/disable sync operation to disk on every transaction. When disabled, latency will decrease but data loss may occur in case of crash	true (Range: true/false)
locale_name	Locale used for string comparison	en_US (Range: any valid locale)
zk_servers	Comma-separated list of Zookeeper server:port	`""` (Range: any string)
zk_prefix	Same instance of Zookeeper can be used by multiple aperturedb clusters. Each cluster uses a different prefix to provide isolation between clusters. The config parameter zk_prefix specifies the path for the instance.	`"testing"` (Range: any string)
checkpoints_to_keep	Number of checkpoints that will be kept for recovery	4 (Range: > 0)
seconds_between_checkpoints	Interval in seconds between scheduled checkpoints. At least one new changelog is required; commit count does not trigger an earlier checkpoint.	7200 (2 hours) (Range: > 0)
resources_check_mem_limit	Limit on percentage of memory utilization after which queries are stopped	93 (Range: 1-100)
resources_check_sleep	Number of seconds between resource utilization checks	2 (Range: > 0)
batch_time_to_live	Number of seconds that a batch is kept in memory before being cleaned up	60 (Range: >= 0)
batch_cleaner_interval	Number of seconds between batch cleanup operations	10 (Range: >= 0)
descriptorset_flusher_interval	Number of seconds between descriptor set cleanup operations	1800 (Range: >= 0)
session_token_max_age_sec	Maximum duration of a session, in seconds	36000 (Range: > 0)
refresh_token_max_age_sec	Maximum duration of a refresh token, in seconds	360000 (Range: > 0)

HTTPS origin limits

These optional integer settings control reads from registered HTTPS origins. They do not configure inbound HTTPS or change the HTTP proxy’s request limit. See HTTPS origins for authentication, URL restrictions, and recovery.

HTTPS fetch controls
JSON key / environment suffix	Default	Range	Scope
`https_max_object_size_mb` / `HTTPS_MAX_OBJECT_SIZE_MB`	16 MiB	1–64 MiB	Maximum bytes in one remote object.
`https_timeout_ms` / `HTTPS_TIMEOUT_MS`	10000 ms	1–30000 ms	Maximum time for one fetch, also bounded by the query deadline.
`https_operations_limit` / `HTTPS_OPERATIONS_LIMIT`	4	1–32	Concurrent HTTPS operations/readers per server process.

Prefix the environment suffix with ADB_. Independently, one query has a 64 MiB total download budget, at most 32 HTTPS requests, a 60-second deadline, and at most two active fetches. These per-query limits are not increased by the three settings above. A size check can make a HEAD request in addition to a GET. Split large workloads into smaller queries and reduce concurrency when limits are reached; retries also consume resources.

Advanced settings

These settings control resource limits and background work. Their appropriate values depend on the deployment layout and workload; changes require coordination with the deployment administrator or ApertureData support. The table lists server defaults before package overrides.

Advanced settings
Key	Default	Purpose and JSON range
`storage_operations_limit`	100	Concurrent object-store operations; integer ≥ 1.
`storage_part_size_mb`	8	Multipart/cache part size in MiB; integer 5–512.
`storage_read_cache_parts`	4	Cached parts per reader; integer 1–64. Memory depends on part size.
`storage_retry_limit` / `storage_retry_delay_ms`	5 / 200	Retry count (integer ≥ 0) and initial backoff in ms (integer ≥ 1).
`objects_partition_count` / `objects_directory_count`	4 / 4096	Object-store layout; integers ≥ 1. Do not change an existing layout casually.
`resources_max_mem_limit`	0	Memory reference limit in bytes; 0 selects detected system memory.
`resources_max_storage` / `resources_check_storage_limit`	0 / 99	Storage reference limit in GiB (0 disables this limit) and percentage threshold (number 0–100).
`resources_check_kill_timer`	2	Time queries remain aborted after exceeding the memory threshold, in seconds; integer ≥ 1.
`task_executor_threads`	100	Executor thread count; integer ≥ 1.
`enable_blacklist`	0	Connection blacklist switch; JSON integer 0 or 1, not a JSON boolean.
`max_failed_connections` / `blacklist_time_minutes`	10 / 5	Blacklist failure threshold and duration in minutes; integers ≥ 1.
`session_cache_max_age_sec`	10	Session-cache refresh interval in seconds; integer ≥ 1.
`kvgd_db_inc_size`	0	Graph mapping growth increment in MB; integer ≥ 0.
`kvgd_readahead` / `validate_write_txn`	false / false	Graph read-ahead and additional write validation; booleans.
`merge_write_request_upto`	0	Internal write-merging control; integer ≥ 0.
`enable_debug` / `disable_add_image`	false / false	Debug behavior and disabling AddImage; booleans.
`refresh_dset_on_startup` / `prevent_telemetry_user_deletion`	false / false	Descriptor startup refresh and protection of the telemetry user; booleans.

more-info is a string annotation accepted in the JSON file; it changes no server behavior and has no environment override.

ADB_HOST_IP is an environment-only server setting for the advertised host identity; its default is the machine hostname. host_ip is not an accepted JSON key. ADB_CHECKPOINT_NOW is an internal checkpointer control, not a normal server configuration key.

Deployment settings and process boundaries

A client first reaches Lenz for the native protocol, or the web proxy and Lenz for REST. The database is a separate backend. Each process reads its own configuration; changing a database variable does not configure the gateway.

Where to configure a setting
Consumer / purpose	Compose	Helm	OpenTofu
Database bootstrap password	`ADB_MASTER_KEY`	`masterKey.password` or `masterKey.existingSecret`	`master_key.password` or `master_key.existing_secret`
Database storage	`ADB_STORAGE_TYPE`, `ADB_STORAGE_BUCKET_NAME`, `ADB_STORAGE_CREDENTIALS` in distributed-cloud	`storage.type`, `storage.bucket`, `storage.credentials` / `existingSecret`	`storage.type`, `storage.bucket`, `storage.credentials` / `existing_secret`
Database HTTPS fetch controls	Custom Compose override for each database service’s `environment`; the published environment template does not forward these keys.	`aperturedb.extraEnv.ADB_HTTPS_*`	`aperturedb.extra_env` map with `ADB_HTTPS_*` keys
Lenz native TLS	`LNZ_FORCE_SSL`; default `false`	Enabled by the chart’s Lenz template	Enabled by the module’s Lenz configuration
Web HTTPS certificates	`TLS_CERT_DIR` and certificate filenames	`tls` settings	`tls` settings
External HTTP request size	`HTTP_MAX_BODY_SIZE`; default `256m`	Ingress-controller configuration; bundled controller uses `ingress-nginx.controller.config.proxy-body-size`	Ingress-controller configuration; bundled controller uses `ingress_nginx.controller.config["proxy-body-size"]`
Published native port	`ADB_TCP_PORT`; default `55555`	`lenz-external` service, port `55555`	`lenz-external` service, port `55555`

All three packages set backend ADB_FORCE_SSL=false and use Lenz for native client TLS. In Helm and OpenTofu, native TLS is enabled by default; Compose requires LNZ_FORCE_SSL=true to enforce it. HTTP TLS is configured separately. A certificate alone does not enable Compose’s native TLS requirement.

Compose substitutes only variables named by its template. Exporting an arbitrary ADB_* variable on the host does not inject it into a container. Helm’s aperturedb.extraEnv and OpenTofu’s aperturedb.extra_env add variables to database containers; use the separate Lenz and checkpointer maps for those processes. Prefer named package values when available, and inspect rendered configuration before introducing a duplicate environment key. For examples and lifecycle commands, see Deploying ApertureDB.

Config File Example

This example sets common parameters to their default values. Omitted parameters use their defaults. For a new database, also set ADB_MASTER_KEY to a strong password before starting the server.

{
    "port": 55555,
    "max_simultaneous_clients": 500,
    "max_connection_message_size_mb": 0,
    "force_ssl": true,
    "db_root_path": "db",
    "storage_type": "ext4",
    "log_path": "/tmp",
    "log_level": 1,
    "verbose_log_level": -1,
    "log_cerr_threshold": 3,
    "batch_cleaner_interval": 10,
    "batch_time_to_live": 60,
    "resources_check_sleep": 2,
    "resources_check_mem_limit": 93
}

Default Directories Structure

ApertureDB creates the following directories under its default data path:

db
├── acl
├── binlogs
├── descriptors
├── graph
├── objects
└── tmp

Parameters​

HTTPS origin limits​

Advanced settings​

Deployment settings and process boundaries​

Config File Example​

Default Directories Structure​